<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>S-XML-RPC</title>
  <link rel="stylesheet" type="text/css" href="style.css"/>
  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
</head>

<body>
  <div class="header">
    <h1>S-XML-RPC</h1>
  </div>

  <p>
    S-XML-RPC is an implementation of <a href="http://www.xmlrpc.com">XML-RPC</a> in Common Lisp for both client and server.
    Originally it was written by <a href="http://homepage.mac.com/svc">Sven Van Caekenberghe</a>.
    It is now being maintained by <a href="http://homepage.mac.com/svc">Sven Van Caekenberghe</a>,
    <a href="http://constantly.at">Rudi Schlatte</a> and <a href="http://www.cs.indiana.edu/~bmastenb">Brian Mastenbrook</a>.
    S-XML-RPC is using <a href="http://common-lisp.net/project/s-xml">S-XML</a> as parser.
  </p>

    <p>
      XML-RPC is a de facto standard for making remote procedure calls between software running on disparate operating systems, running in different environments and implemented using different languages. XML-RPC is using HTTP as the transport and XML as the encoding. XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned. The protocol is described in detail on <a href="http://www.xmlrpc.com/">http://www.xmlrpc.com/</a>. Some key features (both positive and negative) of the XML-RPC protocol are:
      <ul>
	<li>It is a published protocol implemented in a variety of languages and operating systems.</li>
	<li>It allows communication between applications implemented in different languages.</li>
	<li>It allows communication over the internet and through firewalls.</li>
	<li>It is not intended for time-critical communications, or for the transmission of large volumes of data.</li>
	<li>It is an asymmetrical protocol allowing calls from the client to the server but not callbacks from the server to the client.</li>
	<li>It is a very simple protocol that it not defined, controlled or endorsed by a standards body.</li>
	<li>It works.</li>
      </ul>
    </p>

<h3>Download</h3>
<p>
  You can download the LLGPL source code and documentation as <a href="s-xml-rpc.tgz">s-xml-rpc.tgz</a> 
  (signature: <a href="s-xml-rpc.tgz.asc">s-xml-rpc.tgz.asc</a> for which the public key can be found 
  in the <a href="http://common-lisp.net/keyring.asc">common-lisp.net keyring</a>) 
  (build and/or install with ASDF). 
  There is also <a href="http://common-lisp.net/cgi-bin/viewcvs.cgi/?cvsroot=s-xml-rpc">CVS</a> access.
</p>

<h3>API</h3>
<p>
  The plain API exported by the package S-XML-RPC (automatically generated by LispDoc) 
  is available in <a href="S-XML-RPC.html">S-XML-RPC.html</a>.
</p>

    <h2>
      Usage
    </h2>
    <h3>
      Client
    </h3>
    <p>
      Making an XML-RPC call is a two step process: first you encode the call, then you make the call.
      <pre>? (xml-rpc-call (encode-xml-rpc-call "currentTime.getCurrentTime") :host "time.xmlrpc.com")
#&lt;XML-RPC-TIME 20021216T06:36:33&gt;

? (xml-rpc-call (encode-xml-rpc-call "examples.getStateName" 41) :host "betty.userland.com")
"South Dakota"</pre>
      If you are behind an HTTP proxy, you have to pass that information along using keyword arguments. For all keyword arguments, there are default global variables (because most of the time you talk to the same host).
      <pre>? (xml-rpc-call (encode-xml-rpc-call "currentTime.getCurrentTime") :host "time.xmlrpc.com" 
                                                                   :proxy-host "myproxy" 
                                                                   :proxy-port 8080)</pre>
      When all goes well, an XML-RPC call returns a result that is decoded into a Common Lisp value. A number of things can go wrong:
      <ul>
	<li>There could be a problem encoding the call.</li>
	<li>There could be a problem in the networking, up to the HTTP server responding with a code different from 200 OK.</li>
	<li>The result of the call could be an XML-RPC fault: this is how the server responds to an error that occured on the server while executing the call there.</li>
	<li>There could be a problem decoding the call's result.</li>
      </ul>
      At the moment, all these cases are reported by the standard error mechanism. Later we could use different condition types. There are two structs, xml-rpc-time and xml-rpc-struct, that represent two XML-RPC types, iso8601.dateTime and struct respectively. Two convenience functions with the same name come in handy when creating these structs:
      <pre>? (xml-rpc-struct :foo 1 :bar -1)
#&lt;#XML-RPC-STRUCT (:BAR . -1) (:FOO . 1)&gt;
	
? (xml-rpc-time 3000000000)
#&lt;XML-RPC-TIME 19950125T06:20:00&gt;</pre>					
      The function <tt>xml-rpc-aserve:xml-rpc-call-aserve</tt> does the same thing, but uses the (portable) aserve HTTP client API for the networking.
    </p>
    <p>
      The unit tests in the subdirectory <tt>test</tt> can serve as (executable) examples. A more complicated example is the server and client implementation of some tests in <tt>validator1.lisp</tt>. Remember that XML-RPC method (function) names are case-sensitive, as are the names of XML-RPC structure members.
    </p>

    <h3>
      Server
    </h3>
    <p>
      Only a single function call is needed to get the server up and running:
      <pre>? (start-xml-rpc-server :port 8080)</pre> From now on, your
      lisp image becomes an XML-RPC server, listening for HTTP
      requests on port 8080.  By default the
      functions <tt>system.listMethods</tt>, <tt>system.methodSignature</tt>, 
      <tt>system.methodHelp</tt> and <tt>system.multicall</tt> are
      available.  You can export additional functions from the server
      by importing symbols in the package contained
      in <tt>*xml-rpc-package*</tt> (by default, this is the package
      S-XML-RPC-EXPORTS).  <tt>(use-package :common-lisp
      :s-xml-rpc-exports)</tt> makes all of Common Lisp available via
      xml-rpc.
    </p>
  <p>
      In more detail, this is what happens:
      <ul>
	<li>The XML-RPC call arrives as XML encoded characters in the body of an HTTP POST request</li>
	<li>The characters received are parsed by the XML parser and decoded on the fly (using a SAX-like interface) following XML-RPC semantics into a a string method name and a possibly empty list of Lisp objects that are the arguments</li>
	<li>The value of <tt>*xml-rpc-call-hook*</tt> is applied on the string method name and optional argument list</li>
	<li>The default value of <tt>*xml-rpc-call-hook*</tt>
	  is <tt>execute-xml-rpc-call</tt> which looks for a function
	  with the given name in the package <tt>*xml-rpc-package*</tt>
	  (whose default value is the XML-RPC-EXPORTS package) and
	  applies the function bound to that name to the argument list
	  (if any)</li>
	<li>The result is encoded as an XML-RPC result and returned to the client</li>
	<li>If anything goes wrong in any of these steps, a Lisp
	condition is thrown which is caught and then encoded as an XML-RPC fault and returned to the client</li>
      </ul>
      Customization points are <tt>*xml-rpc-package*</tt> and <tt>*xml-rpc-call-hook*</tt>.
      Setting the variable <tt>xml-rpc::*xml-rpc-debug*</tt> to <tt>t</tt> makes the server more verbose.
      Note that XML-RPC method names are case sensitive: for example, clients have specify "LISP-IMPLEMENTATION-TYPE" for the corresponding Lisp function; a server has to define a function named <tt>|login|</tt> if his clients look for an implementation of "login". 
    </p>
    <p>
      AppleScript can make client-side XML-RPC calls. So provided you
      have your lisp XML-RPC server running and have imported + in
      XML-RPC-EXPORTS, you can have lisp do the math like this:
      <pre>tell application "http://localhost:8080/RPC2"
  set call_result to call xmlrpc {method name:"+", parameters:{10, 20, 30}}
end tell
display dialog the call_result buttons {"OK"}</pre>
      Calling the functions <tt>xml-rpc-aserve:start-xml-rpc</tt> and <tt>xml-rpc-aserve:publish-aserve-xml-rpc-handler</tt> does the same thing but uses the (portable) aserve server framework to handle incoming HTTP requests.
    </p>

    <h3>
      Type Mapping
    </h3>
    <p>
      This XML-RPC implementation for Common Lisp maps types as in the following table. There is a small difference between what types are accepted by the encoder and what types are returned by the decoder.
    </p>
    <p>
      <table border="1">
	<tr>
	  <td>
	    XML-RPC Type
	  </td>
	  <td>
	    Accepted Comon Lisp Type
	  </td>
	  <td>
	    Returned Common Lisp Type
	  </td>
	</tr>
	<tr>
	<tr>
	  <td>
	    string
	  </td>
	  <td>
	    string
	  </td>
	  <td>
	    string
	  </td>
	</tr>
	<td>
	  int, i4
	</td>
	<td>
	  integer
	</td>
	<td>
	  integer
	</td>
	</tr>
	<tr>
	  <td>
	    boolean
	  </td>
	  <td>
	    t or nil
	  </td>
	  <td>
	    t or nil
	  </td>
	</tr>
	<tr>
	  <td>
	    double
	  </td>
	  <td>
	    float
	  </td>
	  <td>
	    float
	  </td>
	</tr>
	<tr>
	  <td>
	    base64
	  </td>
	  <td>
	    any array of 1 dimension with at least (unsigned-byte 8) as element type
	  </td>
	  <td>
	    an array of 1 dimension with (unsigned-byte 8) as element type
	  </td>
	</tr>
	<tr>
	  <td>
	    is08601.dateTime
	  </td>
	  <td>
	    struct xml-rpc-time
	  </td>
	  <td>
	    struct xml-rpc-time
	  </td>
	</tr>
	<tr>
	  <td>
	    array
	  </td>
	  <td>
	    list or vector
	  </td>
	  <td>
	    list
	  </td>
	</tr>
	<tr>
	  <td>
	    struct
	  </td>
	  <td>
	    struct xml-rpc-struct
	  </td>
	  <td>
	    struct xml-rpc-struct
	  </td>
	</tr>
      </table>
    <p>
      Later, generic functions to encode and decode arbitrary CLOS instances could be added.
    </p>

   <h3>
      Base64
    </h3>
    <p>
      The code in the package "S-BASE64" is an implementation of Base64 encoding and decoding (part of RFC 1521). Encoding takes bytes (a binary stream or a byte array) and produces characters (a character stream or a string). Decoding goes the other way.
    </p>

<h3>Release History</h3>

<ul>
  <li>today: project moved to common-lisp.net</li>
  <li>release 8, May 9, 2004: added *xml-rpc-authorization* header option (contributed by Nik Gaffney)</li>
  <li>release 7, March 10, 2004: reorganized code to facilitate porting (added package.lisp and sysdeps.lisp, removed run-xml-rpc-server), integrated contributions from Rudi Schlatte and Brian Mastenbrook; SBCL is now supported; fixed a bug where empty strings were turned into nil, added a test</li>
  <li>release 6, Januari 21, 2004: ported to LispWorks, added *xml-rpc-package*, *xml-rpc-call-hook* and execute-xml-rpc-call</li>
  <li>release 5, Januari 20, 2004: added ASDF support, included some contributed patches</li>
  <li>release 4, June 10, 2003: tracking a minor, but incompatible change in the XML parser</li>
  <li>release 3, May 25, 2003: the XML parser has been put in a separate package, we are using the more efficient SAX interface of the parser, improved documentation</li>
  <li>release 2, Januari 6, 2003: we now pass the <a href="http://validator.xmlrpc.com">XML-RPC validator tests</a>, various important bug fixes, improved documentation</li>
  <li>release 1, December 15, 2002: first public release of working code, not optimized, limited testing</li>
</ul>

<h3>Mailing Lists</h3>

<ul>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-rpc-cvs">S-XML-RPC-CVS mailing list info</a></li>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-rpc-devel">S-XML-RPC-DEVEL mailing list info</a></li>
  <li><a href="http://common-lisp.net/mailman/listinfo/s-xml-rpc-announce">S-XML-RPC-ANNOUNCE mailing list info</a></li>
</ul>

  <p>CVS version $Id: index.html,v 1.4 2004/07/08 19:36:53 scaekenberghe Exp $</p>

  <div class="footer">
    <p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>  
  </div>
  
  <div class="check">
    <a href="http://validator.w3.org/check/referer">Valid XHTML 1.0 Strict</a>
    <a href="http://jigsaw.w3.org/css-validator/check/referer">Valid CSS</a>
  </div>
</body>
</html>
